/**
 *    Copyright 2009-2019 the original author or authors.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
package org.apache.ibatis.reflection;

import org.apache.ibatis.reflection.invoker.GetFieldInvoker;
import org.apache.ibatis.reflection.invoker.Invoker;
import org.apache.ibatis.reflection.invoker.MethodInvoker;
import org.apache.ibatis.reflection.invoker.SetFieldInvoker;
import org.apache.ibatis.reflection.property.PropertyNamer;

import java.lang.reflect.*;
import java.util.*;
import java.util.Map.Entry;

/**
 * 简化{@link #type}反射操作的对象。
 * <p>
 * 此类表示一组缓存的类定义信息,允许在属性名称和getter / setter方法之间轻松映射。
 * This class represents a cached set of class definition information that
 * allows for easy mapping between property names and getter/setter methods.
 *
 * @author Clinton Begin
 */
public class Reflector {
    /**
     * 被封装的java对象的类型
     */
    private final Class<?> type;
    /**
     * {@link #type}的可读属性名称集合
     */
    private final String[] readablePropertyNames;
    /**
     * {@link #type}的可写属性名称集合
     */
    private final String[] writeablePropertyNames;
    /**
     * {@link #type}的set方法和执行器的映射列表
     */
    private final Map<String, Invoker> setMethods = new HashMap<>();
    /**
     * {@link #type}get方法集合和执行器的映射列表
     */
    private final Map<String, Invoker> getMethods = new HashMap<>();
    /**
     * set字段类型
     * 字段名称=>字段类型
     */
    private final Map<String, Class<?>> setTypes = new HashMap<>();
    /**
     * get字段类型
     * 字段名称=>字段类型
     */
    private final Map<String, Class<?>> getTypes = new HashMap<>();
    /**
     * {@link #type}的默认构造函数
     */
    private Constructor<?> defaultConstructor;
    /**
     * {@link #type}的大小写不敏感的属性集合，全大写属性名->属性名
     */
    private Map<String, String> caseInsensitivePropertyMap = new HashMap<>();

    public Reflector(Class<?> clazz) {
        // 被封装的JAVA类型
        type = clazz;
        // 配置默认构造方法
        addDefaultConstructor(clazz);
        // 配置以get/is开头的方法集合
        addGetMethods(clazz);
        // 配置set方法
        addSetMethods(clazz);
        // 添加字段集合
        addFields(clazz);

        // 配置可读字段名称集合
        readablePropertyNames = getMethods.keySet().toArray(new String[getMethods.keySet().size()]);
        // 配置可写字段名称集合
        writeablePropertyNames = setMethods.keySet().toArray(new String[setMethods.keySet().size()]);

        // 转换为大写，并放入caseInsensitivePropertyMap中，便于后期查找
        for (String propName : readablePropertyNames) {
            caseInsensitivePropertyMap.put(propName.toUpperCase(Locale.ENGLISH), propName);
        }
        for (String propName : writeablePropertyNames) {
            caseInsensitivePropertyMap.put(propName.toUpperCase(Locale.ENGLISH), propName);
        }
    }

    private void addDefaultConstructor(Class<?> clazz) {
        // 获取所有的构造方法
        Constructor<?>[] consts = clazz.getDeclaredConstructors();
        for (Constructor<?> constructor : consts) {
            if (constructor.getParameterTypes().length == 0) {
                // 获取无参构造
                this.defaultConstructor = constructor;
            }
        }
    }

    private void addGetMethods(Class<?> cls) {
        // 用于解决方法冲突，方法的重载和重写都会导致一个属性对应多个方法
        Map<String, List<Method>> conflictingGetters = new HashMap<>();
        // 获取被处理的类的所有方法
        Method[] methods = getClassMethods(cls);
        for (Method method : methods) {
            // 忽略所有有入参的getter方法
            if (method.getParameterTypes().length > 0) {
                continue;
            }
            String name = method.getName();
            // 获取名称已get/is开头，且不是get/is的方法。
            if ((name.startsWith("get") && name.length() > 3)
                    || (name.startsWith("is") && name.length() > 2)) {
                // 将方法转换为属性名称
                name = PropertyNamer.methodToProperty(name);
                // 记录每一个属性名称对应的方法集合，生成用于解决方法冲突的集合
                addMethodConflict(conflictingGetters, name, method);
            }
        }
        // 处理方法冲突
        resolveGetterConflicts(conflictingGetters);
    }

    private void resolveGetterConflicts(Map<String, List<Method>> conflictingGetters) {
        // 期望能够从重载的方法中获取最终的候选方法
        // 最优`getter`方法计算规则如下：
        //      如果属性对应的多个方法返回类型一致，表示该方法同时有`get`和`is`开头的两个方法，
        //      除了`boolean`类型的属性，其余类型的属性都不允许有两种`getter`方法,如果是`boolean`类型的属性，优先使用`is`开头的方法。
        //      如果属性对应的多个方法返回类型不一致,那么多个方法返回值之间必须存在继承关系，
        //      此时就尽可能选择返回值类型更精确的的方法作为最优方法。
        for (Entry<String, List<Method>> entry : conflictingGetters.entrySet()) {
            // 保存最终采用的方法
            Method winner = null;
            // 当前属性名称
            String propName = entry.getKey();
            for (Method candidate : entry.getValue()) {
                // 处理每一个有效方法
                if (winner == null) {
                    // 第一个方法赋值后会跳过处理
                    winner = candidate;
                    continue;
                }
                // 获取目前胜出的方法的返回类型
                Class<?> winnerType = winner.getReturnType();
                // 获取当前候选方法的返回类型
                Class<?> candidateType = candidate.getReturnType();
                if (candidateType.equals(winnerType)) {
                    // 两个方法返回类型一致，但是不是boolean类型
                    if (!boolean.class.equals(candidateType)) {
                        // 这里单独拆出来boolean类型，是因为在javabean规范中，他可以同时有`get*()`和`is*()`方法。
                        // 非boolean类型的属性同时有了两个getter方法，
                        // 比如name属性同时包含了`getName()`和`isName()`这两个方法。
                        throw new ReflectionException(
                                "Illegal overloaded getter method with ambiguous type for property "
                                        + propName + " in class " + winner.getDeclaringClass()
                                        + ". This breaks the JavaBeans specification and can cause unpredictable results.");
                    } else if (candidate.getName().startsWith("is")) {
                        // 针对boolean类型的属性，如果同时有`get*()`和`is*()`方法优先选择is开头方法。
                        winner = candidate;
                    }
                } else if (candidateType.isAssignableFrom(winnerType)) {
                    // 候选方法的返回值是目前胜利方法返回值的超类，不需要处理，使用范围较小的子类。
                    // OK getter type is descendant
                } else if (winnerType.isAssignableFrom(candidateType)) {
                    // 候选方法的返回值是目前胜利方法返回值的子类,交换胜利省份
                    winner = candidate;
                } else {
                    // 重载方法的返回值类型无任何关系。
                    throw new ReflectionException(
                            "Illegal overloaded getter method with ambiguous type for property "
                                    + propName + " in class " + winner.getDeclaringClass()
                                    + ". This breaks the JavaBeans specification and can cause unpredictable results.");
                }
            }
            // 保存getter方法
            addGetMethod(propName, winner);
        }
    }

    private void addGetMethod(String name, Method method) {
        if (isValidPropertyName(name)) {
            // 保存到getter方法中
            getMethods.put(name, new MethodInvoker(method));
            // 获取方法的返回类型(移除泛型转换为实际类型)
            Type returnType = TypeParameterResolver.resolveReturnType(method, type);
            // 保存属性及其对应的java类型的关系
            getTypes.put(name, typeToClass(returnType));
        }
    }

    private void addSetMethods(Class<?> cls) {
        // 因为重载而产生冲突的setter方法集合
        Map<String, List<Method>> conflictingSetters = new HashMap<>();
        // 获取需要处理的所有方法
        Method[] methods = getClassMethods(cls);
        for (Method method : methods) {
            String name = method.getName();
            // 以set开头，且有且只有一个入参
            if (name.startsWith("set") && name.length() > 3) {
                if (method.getParameterTypes().length == 1) {
                    // 获取对应的属性名称
                    name = PropertyNamer.methodToProperty(name);
                    // 保存方法
                    addMethodConflict(conflictingSetters, name, method);
                }
            }
        }
        // 处理setter方法冲突
        resolveSetterConflicts(conflictingSetters);
    }

    private void addMethodConflict(Map<String, List<Method>> conflictingMethods, String name, Method method) {
        // 如果不存在指定属性名对应的方法列表，则新建一个方法列表
        List<Method> list = conflictingMethods.computeIfAbsent(name, k -> new ArrayList<>());
        // 保存方法
        list.add(method);
    }

    private void resolveSetterConflicts(Map<String, List<Method>> conflictingSetters) {
        for (String propName : conflictingSetters.keySet()) {
            // 处理每个属性对应的setter方法集合

            // 获取属性对应的setter方法集合
            List<Method> setters = conflictingSetters.get(propName);
            // 尝试从getTypes中获取到属性对应的类型
            Class<?> getterType = getTypes.get(propName);
            // 最终匹配的方法
            Method match = null;
            ReflectionException exception = null;
            for (Method setter : setters) {
                // 获取入参类型
                Class<?> paramType = setter.getParameterTypes()[0];
                if (paramType.equals(getterType)) {
                    // should be the best match
                    // 方法入参类型和属性类型一致，那他就是最佳选型
                    match = setter;
                    break;
                }
                if (exception == null) {
                    try {
                        // 尝试获取两个方法中更好的setter方法
                        match = pickBetterSetter(match, setter, propName);
                    } catch (ReflectionException e) {
                        // there could still be the 'best match'
                        match = null;
                        exception = e;
                    }
                }
            }
            if (match == null) {
                throw exception;
            } else {
                // 保存setter方法
                addSetMethod(propName, match);
            }
        }
    }

    /**
     * 该方法的作用是为指定的属性选择一个更好的setter方法定义。
     * setter方法的选择取决于两个setter方法的入参的关系，如果两个方法的入参类型没有关联，将会导致异常。
     * 否则则会获取两个入参类型中相对更精确地方法。
     *
     * @param setter1  第一种setter方法
     * @param setter2  第二种setter方法
     * @param property 属性名
     * @return 最佳setter方法
     */
    private Method pickBetterSetter(Method setter1, Method setter2, String property) {
        if (setter1 == null) {
            return setter2;
        }
        // 分别获取两个方法的入参
        Class<?> paramType1 = setter1.getParameterTypes()[0];
        Class<?> paramType2 = setter2.getParameterTypes()[0];

        // 获取两个类中定义更精确的那个
        if (paramType1.isAssignableFrom(paramType2)) {
            return setter2;
        } else if (paramType2.isAssignableFrom(paramType1)) {
            return setter1;
        }
        throw new ReflectionException("Ambiguous setters defined for property '" + property + "' in class '"
                + setter2.getDeclaringClass() + "' with types '" + paramType1.getName() + "' and '"
                + paramType2.getName() + "'.");
    }

    private void addSetMethod(String name, Method method) {
        if (isValidPropertyName(name)) {
            // 保存属性和setter方法执行器的关系
            setMethods.put(name, new MethodInvoker(method));
            // 获取方法实际入参类型(移除泛型转换为实际类型)
            Type[] paramTypes = TypeParameterResolver.resolveParamTypes(method, type);
            // 保存属性及其setter方法入参类型关系
            setTypes.put(name, typeToClass(paramTypes[0]));
        }
    }

    private Class<?> typeToClass(Type src) {
        Class<?> result = null;
        if (src instanceof Class) {
            // 普通对象
            result = (Class<?>) src;
        } else if (src instanceof ParameterizedType) {
            // 处理参数化泛型，获取泛型所属类型，例如:Map<K,V> 得到Map。
            result = (Class<?>) ((ParameterizedType) src).getRawType();
        } else if (src instanceof GenericArrayType) {
            // 获取泛型数组中元素的类型
            Type componentType = ((GenericArrayType) src).getGenericComponentType();
            if (componentType instanceof Class) {
                // 泛型数组中元素类型是Class
                result = Array.newInstance((Class<?>) componentType, 0).getClass();
            } else {
                // 泛型数组中元素类型还是泛型
                // 递归处理
                Class<?> componentClass = typeToClass(componentType);
                result = Array.newInstance(componentClass, 0).getClass();
            }

        }

        if (result == null) {
            // src是一个TypeVariable或者WildcardType
            result = Object.class;
        }
        return result;
    }

    private void addFields(Class<?> clazz) {
        // 获取所有字段定义
        Field[] fields = clazz.getDeclaredFields();
        for (Field field : fields) {
            // 只处理没有getter/setter方法的属性
            if (!setMethods.containsKey(field.getName())) {
                // issue #379 - removed the check for final because JDK 1.5 allows
                //                // modification of final fields through reflection (JSR-133). (JGB)
                //                // pr #16 - final static can only be set by the classloader
                int modifiers = field.getModifiers();
                if (!(Modifier.isFinal(modifiers) && Modifier.isStatic(modifiers))) {
                    // 处理非静态常量
                    addSetField(field);
                }
            }
            if (!getMethods.containsKey(field.getName())) {
                addGetField(field);
            }
        }
        if (clazz.getSuperclass() != null) {
            // 递归处理父类
            addFields(clazz.getSuperclass());
        }
    }

    private void addSetField(Field field) {
        if (isValidPropertyName(field.getName())) {
            // 配置字段的setter方法
            setMethods.put(field.getName(), new SetFieldInvoker(field));
            // 获取该字段类型
            Type fieldType = TypeParameterResolver.resolveFieldType(field, type);
            // 保存字段名称和字段类型的关系
            setTypes.put(field.getName(), typeToClass(fieldType));
        }
    }

    private void addGetField(Field field) {
        if (isValidPropertyName(field.getName())) {
            // 配置字段getter方法
            getMethods.put(field.getName(), new GetFieldInvoker(field));
            // 获取该字段的类型
            Type fieldType = TypeParameterResolver.resolveFieldType(field, type);
            // 保存字段名称和字段类型的关系
            getTypes.put(field.getName(), typeToClass(fieldType));
        }
    }

    /**
     * 校验是否为有效的属性名称
     *
     * @param name 属性名称
     */
    private boolean isValidPropertyName(String name) {
        return !(name.startsWith("$") || "serialVersionUID".equals(name) || "class".equals(name));
    }

    /**
     * Class.getMethods()方法的增强实现，不仅会获取指定类的方法，还会获取指定类实现/继承的父类和接口中定义的方法。
     *
     * @param cls 指定类
     * @return 所有方法
     */
    private Method[] getClassMethods(Class<?> cls) {
        // 去重后的方法集合
        Map<String, Method> uniqueMethods = new HashMap<>();
        // 当前正在处理的java类
        Class<?> currentClass = cls;
        while (currentClass != null && currentClass != Object.class) {
            // currentClass非空，且不是Object类型

            // 缓存器所有方法
            addUniqueMethods(uniqueMethods, currentClass.getDeclaredMethods());

            // we also need to look for interface methods -
            // because the class may be abstract
            Class<?>[] interfaces = currentClass.getInterfaces();
            for (Class<?> anInterface : interfaces) {
                // 处理其所有接口
                addUniqueMethods(uniqueMethods, anInterface.getMethods());
            }
            // 处理父类
            currentClass = currentClass.getSuperclass();
        }
        Collection<Method> methods = uniqueMethods.values();
        return methods.toArray(new Method[methods.size()]);
    }

    private void addUniqueMethods(Map<String, Method> uniqueMethods, Method[] methods) {
        for (Method currentMethod : methods) {
            // 跳过桥接方法
            if (!currentMethod.isBridge()) {
                // 获取方法签名
                String signature = getSignature(currentMethod);
                // check to see if the method is already known
                // if it is known, then an extended class must have
                // overridden a method
                // 如果方法不存在，保存该方法
                if (!uniqueMethods.containsKey(signature)) {
                    uniqueMethods.put(signature, currentMethod);
                }
            }
        }
    }

    /**
     * 为指定的方法生成签名
     *
     * @param method 方法
     * @return 方法签名
     */
    private String getSignature(Method method) {
        StringBuilder sb = new StringBuilder();
        // 处理返回类型
        Class<?> returnType = method.getReturnType();
        if (returnType != null) {
            sb.append(returnType.getName()).append('#');
        }
        // 处理方法名称
        sb.append(method.getName());
        // 处理方法入参
        Class<?>[] parameters = method.getParameterTypes();
        for (int i = 0; i < parameters.length; i++) {
            if (i == 0) {
                sb.append(':');
            } else {
                sb.append(',');
            }
            sb.append(parameters[i].getName());
        }
        return sb.toString();
    }

    /**
     * 检查是否可以控制成员的访问权限
     * Checks whether can control member accessible.
     *
     * @return If can control member accessible, it return {@literal true}
     * @since 3.5.0
     */
    public static boolean canControlMemberAccessible() {
        try {
            SecurityManager securityManager = System.getSecurityManager();
            if (null != securityManager) {
                securityManager.checkPermission(new ReflectPermission("suppressAccessChecks"));
            }
        } catch (SecurityException e) {
            return false;
        }
        return true;
    }

    /**
     * Gets the name of the class the instance provides information for
     *
     * @return The class name
     */
    public Class<?> getType() {
        return type;
    }

    public Constructor<?> getDefaultConstructor() {
        if (defaultConstructor != null) {
            return defaultConstructor;
        } else {
            throw new ReflectionException("There is no default constructor for " + type);
        }
    }

    public boolean hasDefaultConstructor() {
        return defaultConstructor != null;
    }

    public Invoker getSetInvoker(String propertyName) {
        Invoker method = setMethods.get(propertyName);
        if (method == null) {
            throw new ReflectionException("There is no setter for property named '" + propertyName + "' in '" + type + "'");
        }
        return method;
    }

    /**
     * 获取指定属性的getter执行器
     * @param propertyName 属性名称
     * @return getter执行器
     */
    public Invoker getGetInvoker(String propertyName) {
        Invoker method = getMethods.get(propertyName);
        if (method == null) {
            throw new ReflectionException("There is no getter for property named '" + propertyName + "' in '" + type + "'");
        }
        return method;
    }

    /**
     * 获取指定属性setter方法入参的类型
     *
     * @param propertyName 属性名称
     * @return setter方法入参的类型
     */
    public Class<?> getSetterType(String propertyName) {
        Class<?> clazz = setTypes.get(propertyName);
        if (clazz == null) {
            throw new ReflectionException("There is no setter for property named '" + propertyName + "' in '" + type + "'");
        }
        return clazz;
    }

    /**
     * 获取指定名称的属性的可读类型，该类型取决于指定属性的getter方法和属性定义本身
     *
     * @param propertyName 属性名称
     * @return 指定名称的属性的可读类型
     */
    public Class<?> getGetterType(String propertyName) {
        // 获取属性类型
        Class<?> clazz = getTypes.get(propertyName);
        if (clazz == null) {
            throw new ReflectionException("There is no getter for property named '" + propertyName + "' in '" + type + "'");
        }
        // 返回
        return clazz;
    }

    /**
     * 获取可读属性名称集合
     *
     * @return 可读属性名称集合
     */
    public String[] getGetablePropertyNames() {
        return readablePropertyNames;
    }

    /**
     * 获取可写属性名称集合
     *
     * @return 可写属性名称集合
     */
    public String[] getSetablePropertyNames() {
        return writeablePropertyNames;
    }

    /**
     * 检查指定的类是否有指定属性的setter方法
     *
     * @param propertyName - 被检查的属性
     * @return 如果有指定属性的setter方法返回true
     */
    public boolean hasSetter(String propertyName) {
        return setMethods.keySet().contains(propertyName);
    }

    /**
     * 检查指定的类是否有指定属性的getter方法
     *
     * @param propertyName 被检查的属性
     * @return 如果有指定属性的可读方法返回true
     */
    public boolean hasGetter(String propertyName) {
        return getMethods.keySet().contains(propertyName);
    }

    /**
     * 指定属性的实际名称
     *
     * @param name 大小写不敏感的属性名
     * @return 实际的属性名称
     */
    public String findPropertyName(String name) {
        return caseInsensitivePropertyMap.get(name.toUpperCase(Locale.ENGLISH));
    }
}
